The notifications.xml file is responsible for indicating how a given JMX notification should be transformed into an equivalent SNMP trap. The driver behind this transformation is the notification-type attribute, which indicates the type of JMX notification to transform using a given definition. Here is an example notifications.xml file:
<notification-map-list> <mapping notification-type="jboss.snmp.agent.heartbeat" generic="3" specific="0" enterprise="1.2.3.4.5.6.7"> <var-bind-list wrapper-class="org.jboss.jmx.adaptor.snmp.agent.NotificationWrapperSupport"> <var-bind tag="a:uptime" oid="1.2.3.4.5.6.7.5"/> <var-bind tag="a:trapCount" oid="1.2.3.4.5.6.7.6"/> <var-bind tag="n:message" oid="1.2.3.4.5.6.7.7"/> <var-bind tag="n:sequenceNumber" oid="1.2.3.4.5.6.7.8"/> </var-bind-list> </mapping> </notification-map-list>
This notification would catch the "jboss.snmp.agent.heartbeat" notification, and create an SNMP trap with the payload described in each var-bind, according to the var-bind-list wrapper-class. This class defines how such objects are retrieved.
The values contained in generic and specific are to identify the trap, and the OID in enterprise should be the OID of the object that is emitting this trap. The trap can contain an arbitrary amount of <var-bind>s in its payload.. It is in these <var-bind> tags that the binding of values to OIDs gets tricky.
The <var-bind> element, which is much like the <attribute> element inside attributes.xml, is defined like this: <var-bind tag="a:uptime" oid="1.2.3.4.5.6.7.5"/>
A <var-bind> element has two required attributes, and a single optional attribute, for use by the MIB Generator.
|
Name |
Purpose |
Importance |
Default Value |
|
tag |
Used by the default wrapper class to indicate what value to retrieve. |
Required |
Not Applicable |
|
oid |
The OID that should be assigned to the retrieved value. |
Required |
Not Applicable |
|
type |
The SNMP type of this variable binding. Used by the MIB generator |
Optional |
DisplayString |
There are two different actions the MIB generator may take, based on the value of the tag attribute.
|
Value |
Result |
|
a:* |
The OID paired with a tag that has value a:* MUST correspond to an <attirbute> in attributes.xml. |
|
n:*, u:* |
A new MIB Entry is defined for each of these var-binds, with OIDs as defined. They are then included in the notification's definition in the MIB. |
The oid of an a:* tag must have a definition in the MIB, and thus for the MIB Generator's purposes, must have a definition in the attributes.xml. An SNMP trap cannot contain, in its payload, an object which is not defined either in an imported MIB, or in the MIB where the definition of the trap resides. Since it is the only way to have such a definition exist in the generated MIB, this requirement is enforced. This OID is assumed to be a scalar object. There is currently no support for including a table cell's value in the Trap for the snmp-adaptor.
If the tag is n:* or u:*, a new entry in the MIB is defined, using the prefix "jmxNotification" for the name and modifying capitalization for readability. The SYNTAX of this new entry is defined by the type attribute.
This element contains most of the required attributes for the MIB generator. A minimal definition for the snmp-adaptor looks like this:
<mapping notification-type="jboss.snmp.agent.coldstart" generic="0" specific="0" enterprise="1.2.3.4.5.6.7"> <var-bind-list wrapper-class="org.jboss.jmx.adaptor.snmp.agent.NotificationWrapperSupport"> <var-bind tag="a:trapCount" oid="1.2.3.4.5.6.7.6"/> </var-bind-list> </mapping>
The MIB Generator requires more information about the trap in order to create a meaningful entry. Here's an example of a notification.xml that has enough meta-data for proper MIB generation:
<mapping name="jbossAsHeartbeatNotification" notification-type="jboss.snmp.agent.heartbeat" generic="0" specific="3" enterprise="1.3.6.1.4.1.2312.100.1.2" definition-name="jbossAsTraps"> <var-bind-list wrapper-class="org.jboss.jmx.adaptor.snmp.agent.NotificationWrapperSupport"> <var-bind tag="a:trapCount" oid="1.3.6.1.4.1.2312.100.1.1.11"/> </var-bind-list> </mapping>
A table of additional attributes for the <mapping> element is as follows. All values in the "Importance" column are for the MIB Generator, not the snmp-adaptor.
|
Name |
Purpose |
Importance |
Default Value |
|
name |
The name of the notification as it should appear in the MIB |
Required |
Not Applicable |
|
notification-type |
The actual class name of the JMX notification to be intercepted |
Required |
Not Applicable |
|
generic |
Part of the identification of the trap |
Required |
Not Applicable |
|
specific |
Part of the OID of the trap |
Required |
Not Applicable |
|
enterprise |
Part of the OID of the trap. |
Required |
Not Applicable |
|
inform |
A boolean for indicating whether this trap should be an INFORM. |
Optional |
False |
|
security-name |
Indicates the user to be associated with this trap. V3 only. |
Optional |
Not Applicable |
|
definition-name |
The name to associate with the value in the enterprise attribute. |
Required |
Not Applicable |
|
description |
A description about what the notification is for or contains, to be placed into the MIB |
Optional |
"" |
The MIB generator requires more information, and is more strict about this information, than with the attributes.xml. The most important thing is that the oids in the <var-binds> match up to the oids in the attributes.xml. Otherwise, the MIB generator will not generate a valid MIB, and generation will fail.
The OID of a given notification is in the following form, for v2c and v3 traps:
<enterprise>.0.<specific>
Here is an example of the MIB generator's ouput for the notifications.xml given above:
jbossAsHeartbeatNotification NOTIFICATION-TYPE
OBJECTS {
trapCount
}
STATUS current
DESCRIPTION
""
::= { jbossAsTraps 3 }
Since the oid associated with the a:trapCount tag exists in the MIB, the name of that attribute in the MIB is defined as being part of the notification. The OID of this jbossAsHeartbeatNotification is equal to
1.3.6.1.4.1.2312.100.1.2.0.3
jbossAsTraps = <enterprise>.<generic>
and the final number comes from the <specific> attribute.
As an example, here is output of the heartbeat notification (a simple notification sent every so often, indicating that the server is still alive).The notifications.xml defining this SNMP notification has been included in the MIB generation, so the names of the fields have the correct human-readable name listed:
2011-07-14 16:18:53 localhost.localdomain [UDP: [127.0.0.1]:1161->[127.0.0.1]]: DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (536372) 1:29:23.72 SNMPv2-MIB::snmpTrapOID.0 = OID: JBOSS-AS-VARIA::jbossAsHeartbeatNotification SNMPv2-MIB::sysUpTime = STRING: 536372 JBOSS-AS-VARIA::trapCount = STRING: 805 JBOSS-AS-VARIA::jbossJmxNotificationMessage = STRING: heartbeat report JBOSS-AS-VARIA::jbossJmxNotificationSequenceNumber = STRING: 269